\input texinfo

@setfilename guile-xosd.info
@documentencoding UTF-8
@settitle Guile-XOSD Reference Manual

@include version.texi

@copying
Copyright @copyright{} 2016 Alex Kost

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
copy of the license is included in the section entitled ``GNU Free
Documentation License.''
@end copying

@dircategory The Algorithmic Language Scheme
@direntry
* Guile-XOSD: (guile-xosd).     Guile bindings for libxosd.
@end direntry

@titlepage
@title Guile-XOSD Reference Manual
@subtitle for Guile-XOSD @value{VERSION}
@author Alex Kost

@page
@vskip 0pt plus 1filll

@insertcopying
@end titlepage

@contents

@c ----------------------------------------------------------------
@node Top
@top Guile-XOSD

This document describes Guile-XOSD version @value{VERSION}, Guile
bindings for @code{libxosd} library.

@menu
* Introduction::
* Installation::
* API Reference::
* Example::
* Hacking::

Appendices

* GNU Free Documentation License::  The license of this manual.

@end menu

@node Introduction
@chapter Introduction

Guile-XOSD provides the complete set of Guile bindings for
@code{libxosd}, the @uref{http://sourceforge.net/projects/libxosd/,
XOSD} library.

This manual describes only the Guile procedures (@pxref{API
Reference}).  For the documentation on the XOSD itself, see its man
pages and the full and descriptive XOSD manual, which can be found at
@uref{http://ldots.org/xosd-guide/xosd_guide-onepage.html}.

@node Installation
@chapter Installation

Guile-XOSD depends on the following packages:

@itemize
@item @uref{http://gnu.org/software/guile/, GNU Guile}, 2.0.2 or later;
@item @uref{http://sourceforge.net/projects/libxosd/, libxosd}, 2.2 or later.
@end itemize

The latest release of Guile-XOSD can be found at
@uref{https://github.com/alezost/guile-xosd/releases}.  It can be
installed with the usual sequence of commands of the GNU Build System
(@code{./configure && make && make install}).  For more details on the
installation process, see @file{INSTALL} file.

If you want to build Guile-XOSD from a git checkout, you can do it
with the following additional steps (before running
@code{./configure}):

@example
$ git clone https://github.com/alezost/guile-xosd.git
$ cd guile-xosd
$ ./autogen.sh
@end example

@strong{Important:} Guile modules are installed under the configured
@code{prefix}.  A typical module directory is
@file{/usr/local/share/guile/site/2.0/}).  However, Guile does not
search for modules in @file{/usr/local/...}, so most likely you would
want to configure the package using @code{--with-guile-site-dir} and
@code{--with-guile-site-ccache-dir} options, like this:

@example
$ ./configure --with-guile-site-dir=/usr/share/guile/site/2.0 \
              --with-guile-site-ccache-dir=/usr/lib/guile/2.0/site-ccache
@end example

These are the default directories where @file{*.scm} and @file{*.go}
files should go if Guile was installed into @code{/usr}.  Of course,
you can specify any other directories, but make sure to add them to
@code{GUILE_LOAD_PATH} and @code{GUILE_LOAD_COMPILED_PATH} accordingly
(@pxref{Environment Variables,,, guile, The GNU Guile Reference
Manual}).

Alternatively, you can just install Guile-XOSD using the same prefix as was
specified for Guile:

@example
$ ./configure --prefix=/usr
@end example

@node API Reference
@chapter API Reference

This chapter describes the Guile procedures provided by the
Guile-XOSD.  @code{(xosd bindings)} module provides procedures that
have names very similar to the names of @code{libxosd} C procedures,
while @code{(xosd)} module exports procedures with the more
``Schemey'' names.

@menu
* Direct bindings::		@code{(xosd bindings)} module
* Aliases and wrappers::	@code{(xosd)} module
@end menu

@node Direct bindings
@section Direct bindings

This section lists Guile procedures exported by the @code{(xosd
bindings)} module.  These procedures have almost the same names as the
original C procedures provided by the @code{libxosd} library.  Of
course the names are modified to become the regular Scheme names:
@code{_} is replaced by @code{-}, and there are @code{?} and @code{!}
where appropriate, but the rest left unchanged.

For example, all procedures have @code{xosd-} prefix.  Also
color-related procedures in @code{libxosd} have ``colour'' spelling
(e.g., @code{xosd_set_colour}, not @code{xosd_set_color}).  Procedures
from @code{(xosd bindings)} module inherit this spelling.

@include procedures.texi

@node Aliases and wrappers
@section Aliases and wrappers

@code{(xosd)} module provides some wrappers and aliases for all the
procedures described in the previous section.  These procedures are
intended to be more ``Schemey'' and more clear.

The main rules for the names of aliases are:

@itemize @bullet
@item
@code{xosd} part is replaced with @code{osd} and for the most
procedures (if not documented below) it is moved from the first place
of a name to the second one.  For example, @code{show-osd} is an alias
for @code{xosd-show}, @code{set-osd-font!} is an alias for
@code{xosd-set-font!}.

@item
@code{colour} part is replaced with @code{color}.
@end itemize

Above these rules, the following aliases exist:

@table @code
@item kill-osd
Alias for @code{xosd-destroy}.
@item osd-color
Alias for @code{xosd-get-colour}.
@item osd-number-of-lines
Alias for @code{xosd-get-number-lines}.
@item set-osd-position!
Alias for @code{xosd-set-pos!}.
@item osd-on-screen?
@itemx osd-displayed?
Aliases for @code{xosd-onscreen?}.
@item wait-while-osd-on-screen
@itemx wait-while-osd-displayed
Aliases for @code{xosd-wait-until-no-display}.
@end table

Also the following procedures are available:

@deffn {Scheme Procedure} make-osd [#:lines 1] [#:align] [#:position] @
       [#:bar-length] [#:timeout] [#:color] [#:font] @
       [#:horizontal-offset] [#:vertical-offset] [#:outline-offset] @
       [#:shadow-offset] [#:outline-color] [#:shadow-color]
Create and return a new OSD object with the specified parameters.
This procedure calls @code{(xosd-create lines)} and then
@code{set-osd-@dots{}!} for the other specified keywords.
@end deffn

@deffn {Scheme Procedure} toggle-osd osd
Hide or show @var{osd}.
@end deffn

@deffn {Scheme Procedure} display-string-in-osd osd string @
       [line-number 0]
Display @var{string} in the @var{line-number} of @var{osd}.
This is a wrapper around @code{xosd-display-string} procedure.
@end deffn

@deffn {Scheme Procedure} display-percentage-in-osd osd percentage @
       [line-number 0]
Display @var{percentage} in the @var{line-number} of @var{osd}.
This is a wrapper around @code{xosd-display-percentage} procedure.
@end deffn

@deffn {Scheme Procedure} display-slider-in-osd osd percentage @
       [line-number 0]
Display slider @var{percentage} in the @var{line-number} of @var{osd}.
This is a wrapper around @code{xosd-display-slider} procedure.
@end deffn

@node Example
@chapter Example

Now let's look at a simple example of using Guile-XOSD.  The following
piece of code displays ``Hello!'' OSD in the top right corner of your
screen for 3 seconds.

@lisp
@include hello.scm
@end lisp

You can find other examples of using both @code{(xosd)} and
@code{(xosd bindings)} modules in the
@file{<prefix>/share/guile-xosd/examples} directory.

@node Hacking
@chapter Hacking

It is possible to use Guile-XOSD without installation (after running
@code{./configure} and @code{make} but without @code{make install}).
All is needed is setting the following environment variables:

@table @code
@item GUILE_LOAD_PATH
@itemx GUILE_LOAD_COMPILED_PATH
@xref{Environment Variables,,, guile, GNU Guile Reference Manual}.

@item GUILE_XOSD_LIBDIR
Directory where @file{libguile-xosd} library is placed after
compilation.  Usually it is @file{<builddir>/src/.libs}.

@item GUILE_XOSD_DOCDIR
Directory where @file{xosd-procedures.txt} (the file with docstrings
for Guile procedures) is placed.  Usually it is
@file{<srcdir>/modules}.
@end table

Setting them manually is not needed as Guile-XOSD provides
@file{pre-inst-env} and @file{pre-inst-env.el} files for this purpose.

@itemize @bullet
@item
@file{pre-inst-env} is a shell script that sets the required
environment variables, and runs the specified command.  A typical use
is:

@example
$ ./pre-inst-env guile
scheme@@(guile-user)> ,use(xosd)
...
@end example

@item
If you live in Emacs, you may find @file{pre-inst-env.el} more useful.
If you load this file (for example, with @kbd{M-x load-file}), it will
set the environment inside Emacs, so you can run Guile in @kbd{M-x
shell}, or more importantly start Geiser and use Guile-XOSD modules
there.

@end itemize

@node GNU Free Documentation License
@appendix GNU Free Documentation License

@include fdl.texi

@bye
